<html xmlns="http://www.w3.org/1999/xhtml">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
<head>
<title>
    
                Namespaces
             &mdash; 
    Mako 0.8.1 Documentation
</title>

    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/docs.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '#',
          VERSION:     '0.8.1',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>
        <script type="text/javascript" src="_static/jquery.js"></script>
        <script type="text/javascript" src="_static/underscore.js"></script>
        <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Mako 0.8.1 Documentation" href="index.html" />
        <link rel="next" title="Inheritance" href="inheritance.html" />
        <link rel="prev" title="The Mako Runtime Environment" href="runtime.html" />

<link rel="stylesheet" href="_static/site.css"></link>


</head>
<body>
    <div id="wrap">
    <div class="rightbar">


    <div class="slogan">
    Hyperfast and lightweight templating for the Python platform.
    </div>


    </div>

    <a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>

    <hr/>

    









<div id="docs-container">



<div id="docs-header">
    <h1>Mako 0.8.1 Documentation</h1>

    <div id="docs-search">
    Search:
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>

    <div id="docs-version-header">
        Release: <span class="version-num">0.8.1</span>

    </div>

</div>

<div id="docs-top-navigation">
    <div id="docs-top-page-control" class="docs-navigation-links">
        <ul>
            <li>Prev:
            <a href="runtime.html" title="previous chapter">The Mako Runtime Environment</a>
            </li>
            <li>Next:
            <a href="inheritance.html" title="next chapter">Inheritance</a>
            </li>

        <li>
            <a href="index.html">Table of Contents</a> |
            <a href="genindex.html">Index</a>
            | <a href="_sources/namespaces.txt">view source
        </li>
        </ul>
    </div>

    <div id="docs-navigation-banner">
        <a href="index.html">Mako 0.8.1 Documentation</a>
        » 
                Namespaces
             

        <h2>
            
                Namespaces
            
        </h2>
    </div>

</div>

<div id="docs-body-container">

    <div id="docs-sidebar">
    <h3><a href="index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">Namespaces</a><ul>
<li><a class="reference internal" href="#ways-to-call-namespaces">Ways to Call Namespaces</a></li>
<li><a class="reference internal" href="#namespaces-from-regular-python-modules">Namespaces from Regular Python Modules</a></li>
<li><a class="reference internal" href="#declaring-defs-in-namespaces">Declaring Defs in Namespaces</a></li>
<li><a class="reference internal" href="#the-body-method">The <tt class="docutils literal"><span class="pre">body()</span></tt> Method</a></li>
<li><a class="reference internal" href="#built-in-namespaces">Built-in Namespaces</a><ul>
<li><a class="reference internal" href="#local"><tt class="docutils literal"><span class="pre">local</span></tt></a></li>
<li><a class="reference internal" href="#self"><tt class="docutils literal"><span class="pre">self</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#inheritable-namespaces">Inheritable Namespaces</a></li>
<li><a class="reference internal" href="#namespace-api-usage-example-static-dependencies">Namespace API Usage Example - Static Dependencies</a><ul>
<li><a class="reference internal" href="#version-one-use-namespace-attr">Version One - Use <tt class="docutils literal"><span class="pre">Namespace.attr</span></tt></a></li>
<li><a class="reference internal" href="#version-two-use-a-specific-named-def">Version Two - Use a specific named def</a></li>
</ul>
</li>
<li><a class="reference internal" href="#api-reference">API Reference</a></li>
</ul>
</li>
</ul>


    <h4>Previous Topic</h4>
    <p>
    <a href="runtime.html" title="previous chapter">The Mako Runtime Environment</a>
    </p>
    <h4>Next Topic</h4>
    <p>
    <a href="inheritance.html" title="next chapter">Inheritance</a>
    </p>

    <h4>Quick Search</h4>
    <p>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </p>

    </div>

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="namespaces">
<span id="namespaces-toplevel"></span><h1>Namespaces<a class="headerlink" href="#namespaces" title="Permalink to this headline">¶</a></h1>
<p>Namespaces are used to organize groups of defs into
categories, and also to &#8220;import&#8221; defs from other files.</p>
<p>If the file <tt class="docutils literal"><span class="pre">components.html</span></tt> defines these two defs:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## components.html</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;comp1()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    this is comp1</span>
<span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>

<span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;comp2(x)&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    this is comp2, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x"></span>
<span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>you can make another file, for example <tt class="docutils literal"><span class="pre">index.html</span></tt>, that
pulls those two defs into a namespace called <tt class="docutils literal"><span class="pre">comp</span></tt>:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## index.html</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;comp&quot;</span> <span class="na">file=</span><span class="s">&quot;components.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="x">Here&#39;s comp1:  </span><span class="cp">${</span><span class="n">comp</span><span class="o">.</span><span class="n">comp1</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x">Here&#39;s comp2:  </span><span class="cp">${</span><span class="n">comp</span><span class="o">.</span><span class="n">comp2</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">comp</span></tt> variable above is an instance of
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>, a <strong>proxy object</strong> which delivers
method calls to the underlying template callable using the
current context.</p>
<p><tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> also provides an <tt class="docutils literal"><span class="pre">import</span></tt> attribute which can
be used to pull the names into the local namespace, removing the
need to call it via the &#8220;<tt class="docutils literal"><span class="pre">.</span></tt>&#8221; operator. When <tt class="docutils literal"><span class="pre">import</span></tt> is used, the
<tt class="docutils literal"><span class="pre">name</span></tt> attribute is optional.</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">file=</span><span class="s">&quot;components.html&quot;</span> <span class="na">import=</span><span class="s">&quot;comp1, comp2&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="x">Heres comp1:  </span><span class="cp">${</span><span class="n">comp1</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x">Heres comp2:  </span><span class="cp">${</span><span class="n">comp2</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">import</span></tt> also supports the &#8220;<tt class="docutils literal"><span class="pre">*</span></tt>&#8221; operator:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">file=</span><span class="s">&quot;components.html&quot;</span> <span class="na">import=</span><span class="s">&quot;*&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="x">Heres comp1:  </span><span class="cp">${</span><span class="n">comp1</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x">Heres comp2:  </span><span class="cp">${</span><span class="n">comp2</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>The names imported by the <tt class="docutils literal"><span class="pre">import</span></tt> attribute take precedence
over any names that exist within the current context.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In current versions of Mako, usage of <tt class="docutils literal"><span class="pre">import='*'</span></tt> is
known to decrease performance of the template. This will be
fixed in a future release.</p>
</div>
<p>The <tt class="docutils literal"><span class="pre">file</span></tt> argument allows expressions &#8211; if looking for
context variables, the <tt class="docutils literal"><span class="pre">context</span></tt> must be named explicitly:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;dyn&quot;</span> <span class="na">file=</span><span class="s">&quot;${context[&#39;namespace_name&#39;]}&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
</pre></div>
</div>
<div class="section" id="ways-to-call-namespaces">
<h2>Ways to Call Namespaces<a class="headerlink" href="#ways-to-call-namespaces" title="Permalink to this headline">¶</a></h2>
<p>There are essentially four ways to call a function from a
namespace.</p>
<p>The &#8220;expression&#8221; format, as described previously. Namespaces are
just Python objects with functions on them, and can be used in
expressions like any other function:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="n">mynamespace</span><span class="o">.</span><span class="n">somefunction</span><span class="p">(</span><span class="s">&#39;some arg1&#39;</span><span class="p">,</span> <span class="s">&#39;some arg2&#39;</span><span class="p">,</span> <span class="n">arg3</span><span class="o">=</span><span class="s">&#39;some arg3&#39;</span><span class="p">,</span> <span class="n">arg4</span><span class="o">=</span><span class="s">&#39;some arg4&#39;</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>Synonymous with the &#8220;expression&#8221; format is the &#8220;custom tag&#8221;
format, when a &#8220;closed&#8221; tag is used. This format, introduced in
Mako 0.2.3, allows the usage of a &#8220;custom&#8221; Mako tag, with the
function arguments passed in using named attributes:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">mynamespace:somefunction</span> <span class="na">arg1=</span><span class="s">&quot;some arg1&quot;</span> <span class="na">arg2=</span><span class="s">&quot;some arg2&quot;</span> <span class="na">arg3=</span><span class="s">&quot;some arg3&quot;</span> <span class="na">arg4=</span><span class="s">&quot;some arg4&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>When using tags, the values of the arguments are taken as
literal strings by default. To embed Python expressions as
arguments, use the embedded expression format:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">mynamespace:somefunction</span> <span class="na">arg1=</span><span class="s">&quot;${someobject.format()}&quot;</span> <span class="na">arg2=</span><span class="s">&quot;${somedef(5, 12)}&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>The &#8220;custom tag&#8221; format is intended mainly for namespace
functions which recognize body content, which in Mako is known
as a &#8220;def with embedded content&#8221;:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">mynamespace:somefunction</span> <span class="na">arg1=</span><span class="s">&quot;some argument&quot;</span> <span class="na">args=</span><span class="s">&quot;x, y&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    Some record: </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x">, </span><span class="cp">${</span><span class="n">y</span><span class="cp">}</span><span class="x"></span>
<span class="cp">&lt;/%</span><span class="nb">mynamespace:somefunction</span><span class="cp">&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>The &#8220;classic&#8221; way to call defs with embedded content is the <tt class="docutils literal"><span class="pre">&lt;%call&gt;</span></tt> tag:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">call</span> <span class="na">expr=</span><span class="s">&quot;mynamespace.somefunction(arg1=&#39;some argument&#39;)&quot;</span> <span class="na">args=</span><span class="s">&quot;x, y&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    Some record: </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x">, </span><span class="cp">${</span><span class="n">y</span><span class="cp">}</span><span class="x"></span>
<span class="cp">&lt;/%</span><span class="nb">call</span><span class="cp">&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>For information on how to construct defs that embed content from
the caller, see <a class="reference internal" href="defs.html#defs-with-content"><em>Calling a Def with Embedded Content and/or Other Defs</em></a>.</p>
</div>
<div class="section" id="namespaces-from-regular-python-modules">
<span id="namespaces-python-modules"></span><h2>Namespaces from Regular Python Modules<a class="headerlink" href="#namespaces-from-regular-python-modules" title="Permalink to this headline">¶</a></h2>
<p>Namespaces can also import regular Python functions from
modules. These callables need to take at least one argument,
<tt class="docutils literal"><span class="pre">context</span></tt>, an instance of <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a>. A module file
<tt class="docutils literal"><span class="pre">some/module.py</span></tt> might contain the callable:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">my_tag</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
    <span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;hello world&quot;</span><span class="p">)</span>
    <span class="k">return</span> <span class="s">&#39;&#39;</span>
</pre></div>
</div>
<p>A template can use this module via:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;hw&quot;</span> <span class="na">module=</span><span class="s">&quot;some.module&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="cp">${</span><span class="n">hw</span><span class="o">.</span><span class="n">my_tag</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>Note that the <tt class="docutils literal"><span class="pre">context</span></tt> argument is not needed in the call;
the <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> tag creates a locally-scoped callable which
takes care of it. The <tt class="docutils literal"><span class="pre">return</span> <span class="pre">''</span></tt> is so that the def does not
dump a <tt class="docutils literal"><span class="pre">None</span></tt> into the output stream &#8211; the return value of any
def is rendered after the def completes, in addition to whatever
was passed to <a class="reference internal" href="runtime.html#mako.runtime.Context.write" title="mako.runtime.Context.write"><tt class="xref py py-meth docutils literal"><span class="pre">Context.write()</span></tt></a> within its body.</p>
<p>If your def is to be called in an &#8220;embedded content&#8221; context,
that is as described in <a class="reference internal" href="defs.html#defs-with-content"><em>Calling a Def with Embedded Content and/or Other Defs</em></a>, you should use
the <a class="reference internal" href="#mako.runtime.supports_caller" title="mako.runtime.supports_caller"><tt class="xref py py-func docutils literal"><span class="pre">supports_caller()</span></tt></a> decorator, which will ensure that Mako
will ensure the correct &#8220;caller&#8221; variable is available when your
def is called, supporting embedded content:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.runtime</span> <span class="kn">import</span> <span class="n">supports_caller</span>

<span class="nd">@supports_caller</span>
<span class="k">def</span> <span class="nf">my_tag</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
    <span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&lt;div&gt;&quot;</span><span class="p">)</span>
    <span class="n">context</span><span class="p">[</span><span class="s">&#39;caller&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">body</span><span class="p">()</span>
    <span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&lt;/div&gt;&quot;</span><span class="p">)</span>
    <span class="k">return</span> <span class="s">&#39;&#39;</span>
</pre></div>
</div>
<p>Capturing of output is available as well, using the
outside-of-templates version of the <a class="reference internal" href="#mako.runtime.capture" title="mako.runtime.capture"><tt class="xref py py-func docutils literal"><span class="pre">capture()</span></tt></a> function,
which accepts the &#8220;context&#8221; as its first argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.runtime</span> <span class="kn">import</span> <span class="n">supports_caller</span><span class="p">,</span> <span class="n">capture</span>

<span class="nd">@supports_caller</span>
<span class="k">def</span> <span class="nf">my_tag</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
    <span class="k">return</span> <span class="s">&quot;&lt;div&gt;</span><span class="si">%s</span><span class="s">&lt;/div&gt;&quot;</span> <span class="o">%</span> \
            <span class="n">capture</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">context</span><span class="p">[</span><span class="s">&#39;caller&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">body</span><span class="p">,</span> <span class="n">x</span><span class="o">=</span><span class="s">&quot;foo&quot;</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="s">&quot;bar&quot;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="declaring-defs-in-namespaces">
<h2>Declaring Defs in Namespaces<a class="headerlink" href="#declaring-defs-in-namespaces" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tag supports the definition of <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt>s
directly inside the tag. These defs become part of the namespace
like any other function, and will override the definitions
pulled in from a remote template or module:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## define a namespace</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;stuff&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;comp1()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">        comp1</span>
<span class="x">    </span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
<span class="cp">&lt;/%</span><span class="nb">namespace</span><span class="cp">&gt;</span>

<span class="cp">## then call it</span><span class="x"></span>
<span class="cp">${</span><span class="n">stuff</span><span class="o">.</span><span class="n">comp1</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
</div>
<div class="section" id="the-body-method">
<span id="namespaces-body"></span><h2>The <tt class="docutils literal"><span class="pre">body()</span></tt> Method<a class="headerlink" href="#the-body-method" title="Permalink to this headline">¶</a></h2>
<p>Every namespace that is generated from a template contains a
method called <tt class="docutils literal"><span class="pre">body()</span></tt>. This method corresponds to the main
body of the template, and plays its most important roles when
using inheritance relationships as well as
def-calls-with-content.</p>
<p>Since the <tt class="docutils literal"><span class="pre">body()</span></tt> method is available from a namespace just
like all the other defs defined in a template, what happens if
you send arguments to it? By default, the <tt class="docutils literal"><span class="pre">body()</span></tt> method
accepts no positional arguments, and for usefulness in
inheritance scenarios will by default dump all keyword arguments
into a dictionary called <tt class="docutils literal"><span class="pre">pageargs</span></tt>. But if you actually want
to get at the keyword arguments, Mako recommends you define your
own argument signature explicitly. You do this via using the
<tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> tag:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">args=</span><span class="s">&quot;x, y, someval=8, scope=&#39;foo&#39;, **kwargs&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>A template which defines the above signature requires that the
variables <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> are defined, defines default values
for <tt class="docutils literal"><span class="pre">someval</span></tt> and <tt class="docutils literal"><span class="pre">scope</span></tt>, and sets up <tt class="docutils literal"><span class="pre">**kwargs</span></tt> to
receive all other keyword arguments. If <tt class="docutils literal"><span class="pre">**kwargs</span></tt> or similar
is not present, the argument <tt class="docutils literal"><span class="pre">**pageargs</span></tt> gets tacked on by
Mako. When the template is called as a top-level template (i.e.
via <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a>) or via the <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt> tag, the
values for these arguments will be pulled from the <tt class="docutils literal"><span class="pre">Context</span></tt>.
In all other cases, i.e. via calling the <tt class="docutils literal"><span class="pre">body()</span></tt> method, the
arguments are taken as ordinary arguments from the method call.
So above, the body might be called as:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">body</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">someval</span><span class="o">=</span><span class="mi">15</span><span class="p">,</span> <span class="n">delta</span><span class="o">=</span><span class="mi">7</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>The <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> object also supplies a <a class="reference internal" href="runtime.html#mako.runtime.Context.kwargs" title="mako.runtime.Context.kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">kwargs</span></tt></a> accessor, for
cases when you&#8217;d like to pass along whatever is in the context to
a <tt class="docutils literal"><span class="pre">body()</span></tt> callable:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">(</span><span class="o">**</span><span class="n">context</span><span class="o">.</span><span class="n">kwargs</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>The usefulness of calls like the above become more apparent when
one works with inheriting templates. For more information on
this, as well as the meanings of the names <tt class="docutils literal"><span class="pre">self</span></tt> and
<tt class="docutils literal"><span class="pre">next</span></tt>, see <a class="reference internal" href="inheritance.html"><em>Inheritance</em></a>.</p>
</div>
<div class="section" id="built-in-namespaces">
<span id="namespaces-builtin"></span><h2>Built-in Namespaces<a class="headerlink" href="#built-in-namespaces" title="Permalink to this headline">¶</a></h2>
<p>The namespace is so great that Mako gives your template one (or
two) for free. The names of these namespaces are <tt class="docutils literal"><span class="pre">local</span></tt> and
<tt class="docutils literal"><span class="pre">self</span></tt>. Other built-in namespaces include <tt class="docutils literal"><span class="pre">parent</span></tt> and
<tt class="docutils literal"><span class="pre">next</span></tt>, which are optional and are described in
<a class="reference internal" href="inheritance.html"><em>Inheritance</em></a>.</p>
<div class="section" id="local">
<span id="namespace-local"></span><h3><tt class="docutils literal"><span class="pre">local</span></tt><a class="headerlink" href="#local" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">local</span></tt> namespace is basically the namespace for the
currently executing template. This means that all of the top
level defs defined in your template, as well as your template&#8217;s
<tt class="docutils literal"><span class="pre">body()</span></tt> function, are also available off of the <tt class="docutils literal"><span class="pre">local</span></tt>
namespace.</p>
<p>The <tt class="docutils literal"><span class="pre">local</span></tt> namespace is also where properties like <tt class="docutils literal"><span class="pre">uri</span></tt>,
<tt class="docutils literal"><span class="pre">filename</span></tt>, and <tt class="docutils literal"><span class="pre">module</span></tt> and the <tt class="docutils literal"><span class="pre">get_namespace</span></tt> method
can be particularly useful.</p>
</div>
<div class="section" id="self">
<span id="namespace-self"></span><h3><tt class="docutils literal"><span class="pre">self</span></tt><a class="headerlink" href="#self" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">self</span></tt> namespace, in the case of a template that does not
use inheritance, is synonymous with <tt class="docutils literal"><span class="pre">local</span></tt>. If inheritance is
used, then <tt class="docutils literal"><span class="pre">self</span></tt> references the topmost template in the
inheritance chain, where it is most useful for providing the
ultimate form of various &#8220;method&#8221; calls which may have been
overridden at various points in an inheritance chain. See
<a class="reference internal" href="inheritance.html"><em>Inheritance</em></a>.</p>
</div>
</div>
<div class="section" id="inheritable-namespaces">
<h2>Inheritable Namespaces<a class="headerlink" href="#inheritable-namespaces" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tag includes an optional attribute
<tt class="docutils literal"><span class="pre">inheritable=&quot;True&quot;</span></tt>, which will cause the namespace to be
attached to the <tt class="docutils literal"><span class="pre">self</span></tt> namespace. Since <tt class="docutils literal"><span class="pre">self</span></tt> is globally
available throughout an inheritance chain (described in the next
section), all the templates in an inheritance chain can get at
the namespace imported in a super-template via <tt class="docutils literal"><span class="pre">self</span></tt>.</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## base.html</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;foo&quot;</span> <span class="na">file=</span><span class="s">&quot;foo.html&quot;</span> <span class="na">inheritable=</span><span class="s">&quot;True&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span>

<span class="cp">## somefile.html</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">bar</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>This allows a super-template to load a whole bunch of namespaces
that its inheriting templates can get to, without them having to
explicitly load those namespaces themselves.</p>
<p>The <tt class="docutils literal"><span class="pre">import=&quot;*&quot;</span></tt> part of the <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tag doesn&#8217;t yet
interact with the <tt class="docutils literal"><span class="pre">inheritable</span></tt> flag, so currently you have to
use the explicit namespace name off of <tt class="docutils literal"><span class="pre">self</span></tt>, followed by the
desired function name. But more on this in a future release.</p>
</div>
<div class="section" id="namespace-api-usage-example-static-dependencies">
<h2>Namespace API Usage Example - Static Dependencies<a class="headerlink" href="#namespace-api-usage-example-static-dependencies" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tag at runtime produces an instance of
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>.   Programmatic access of <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> can be used
to build various kinds of scaffolding in templates and between templates.</p>
<p>A common request is the ability for a particular template to declare
&#8220;static includes&#8221; - meaning, the usage of a particular set of defs requires
that certain Javascript/CSS files are present.   Using <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> as the
object that holds together the various templates present, we can build a variety
of such schemes.   In particular, the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> has a <tt class="docutils literal"><span class="pre">namespaces</span></tt>
attribute, which is a dictionary of all <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> objects declared.
Iterating the values of this dictionary will provide a <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>
object for each time the <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tag was used, anywhere within the
inheritance chain.</p>
<div class="section" id="version-one-use-namespace-attr">
<span id="namespace-attr-for-includes"></span><h3>Version One - Use <a class="reference internal" href="#mako.runtime.Namespace.attr" title="mako.runtime.Namespace.attr"><tt class="xref py py-attr docutils literal"><span class="pre">Namespace.attr</span></tt></a><a class="headerlink" href="#version-one-use-namespace-attr" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#mako.runtime.Namespace.attr" title="mako.runtime.Namespace.attr"><tt class="xref py py-attr docutils literal"><span class="pre">Namespace.attr</span></tt></a> attribute allows us to locate any variables declared
in the <tt class="docutils literal"><span class="pre">&lt;%!</span> <span class="pre">%&gt;</span></tt> of a template.</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## base.mako</span><span class="x"></span>
<span class="cp">## base-most template, renders layout etc.</span><span class="x"></span>
<span class="x">&lt;html&gt;</span>
<span class="x">&lt;head&gt;</span>
<span class="cp">## traverse through all namespaces present,</span><span class="x"></span>
<span class="cp">## look for an attribute named &#39;includes&#39;</span><span class="x"></span>
<span class="cp">%</span> <span class="k">for</span> <span class="n">ns</span> <span class="ow">in</span> <span class="n">context</span><span class="o">.</span><span class="n">namespaces</span><span class="o">.</span><span class="n">values</span><span class="p">():</span><span class="x"></span>
    <span class="cp">%</span> <span class="k">for</span> <span class="n">incl</span> <span class="ow">in</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">ns</span><span class="o">.</span><span class="n">attr</span><span class="p">,</span> <span class="s">&#39;includes&#39;</span><span class="p">,</span> <span class="p">[]):</span><span class="x"></span>
<span class="x">        </span><span class="cp">${</span><span class="n">incl</span><span class="cp">}</span>
    <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
<span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
<span class="x">&lt;/head&gt;</span>
<span class="x">&lt;body&gt;</span>
<span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x">&lt;/body</span>
<span class="x">&lt;/html&gt;</span>

<span class="cp">## library.mako</span><span class="x"></span>
<span class="cp">## library functions.</span><span class="x"></span>
<span class="cp">&lt;%!</span>
    <span class="n">includes</span> <span class="o">=</span> <span class="p">[</span>
        <span class="s">&#39;&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;mystyle.css&quot;/&gt;&#39;</span><span class="p">,</span>
        <span class="s">&#39;&lt;script type=&quot;text/javascript&quot; src=&quot;functions.js&quot;&gt;&lt;/script&gt;&#39;</span>
    <span class="p">]</span>
<span class="cp">%&gt;</span><span class="x"></span>

<span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;mytag()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    &lt;form&gt;</span>
<span class="x">        </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x">    &lt;/form&gt;</span>
<span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span>

<span class="cp">## index.mako</span><span class="x"></span>
<span class="cp">## calling template.</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.mako&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;foo&quot;</span> <span class="na">file=</span><span class="s">&quot;library.mako&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="cp">&lt;%</span><span class="nb">foo:mytag</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    a form</span>
<span class="cp">&lt;/%</span><span class="nb">foo:mytag</span><span class="cp">&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>Above, the file <tt class="docutils literal"><span class="pre">library.mako</span></tt> declares an attribute <tt class="docutils literal"><span class="pre">includes</span></tt> inside its global <tt class="docutils literal"><span class="pre">&lt;%!</span> <span class="pre">%&gt;</span></tt> section.
<tt class="docutils literal"><span class="pre">index.mako</span></tt> includes this template using the <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tag.  The base template <tt class="docutils literal"><span class="pre">base.mako</span></tt>, which is the inherited parent of <tt class="docutils literal"><span class="pre">index.mako</span></tt> and is reponsible for layout, then locates this attribute and iterates through its contents to produce the includes that are specific to <tt class="docutils literal"><span class="pre">library.mako</span></tt>.</p>
</div>
<div class="section" id="version-two-use-a-specific-named-def">
<h3>Version Two - Use a specific named def<a class="headerlink" href="#version-two-use-a-specific-named-def" title="Permalink to this headline">¶</a></h3>
<p>In this version, we put the includes into a <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt> that
follows a naming convention.</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## base.mako</span><span class="x"></span>
<span class="cp">## base-most template, renders layout etc.</span><span class="x"></span>
<span class="x">&lt;html&gt;</span>
<span class="x">&lt;head&gt;</span>
<span class="cp">## traverse through all namespaces present,</span><span class="x"></span>
<span class="cp">## look for a %def named &#39;includes&#39;</span><span class="x"></span>
<span class="cp">%</span> <span class="k">for</span> <span class="n">ns</span> <span class="ow">in</span> <span class="n">context</span><span class="o">.</span><span class="n">namespaces</span><span class="o">.</span><span class="n">values</span><span class="p">():</span><span class="x"></span>
    <span class="cp">%</span> <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">ns</span><span class="p">,</span> <span class="s">&#39;includes&#39;</span><span class="p">):</span><span class="x"></span>
<span class="x">        </span><span class="cp">${</span><span class="n">ns</span><span class="o">.</span><span class="n">includes</span><span class="p">()</span><span class="cp">}</span>
    <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
<span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
<span class="x">&lt;/head&gt;</span>
<span class="x">&lt;body&gt;</span>
<span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x">&lt;/body</span>
<span class="x">&lt;/html&gt;</span>

<span class="cp">## library.mako</span><span class="x"></span>
<span class="cp">## library functions.</span><span class="x"></span>

<span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;includes()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    &lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;mystyle.css&quot;/&gt;</span>
<span class="x">    &lt;script type=&quot;text/javascript&quot; src=&quot;functions.js&quot;&gt;&lt;/script&gt;</span>
<span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>

<span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;mytag()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    &lt;form&gt;</span>
<span class="x">        </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x">    &lt;/form&gt;</span>
<span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span>


<span class="cp">## index.mako</span><span class="x"></span>
<span class="cp">## calling template.</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.mako&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
<span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;foo&quot;</span> <span class="na">file=</span><span class="s">&quot;library.mako&quot;</span><span class="cp">/&gt;</span><span class="x"></span>

<span class="cp">&lt;%</span><span class="nb">foo:mytag</span><span class="cp">&gt;</span><span class="x"></span>
<span class="x">    a form</span>
<span class="cp">&lt;/%</span><span class="nb">foo:mytag</span><span class="cp">&gt;</span><span class="x"></span>
</pre></div>
</div>
<p>In this version, <tt class="docutils literal"><span class="pre">library.mako</span></tt> declares a <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt> named <tt class="docutils literal"><span class="pre">includes</span></tt>.   The example works
identically to the previous one, except that <tt class="docutils literal"><span class="pre">base.mako</span></tt> looks for defs named <tt class="docutils literal"><span class="pre">include</span></tt>
on each namespace it examines.</p>
</div>
</div>
<div class="section" id="api-reference">
<h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="mako.runtime.Namespace">
<em class="property">class </em><tt class="descclassname">mako.runtime.</tt><tt class="descname">Namespace</tt><big>(</big><em>name</em>, <em>context</em>, <em>callables=None</em>, <em>inherits=None</em>, <em>populate_self=True</em>, <em>calling_uri=None</em><big>)</big><a class="headerlink" href="#mako.runtime.Namespace" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
<p>Provides access to collections of rendering methods, which
can be local, from other templates, or from imported modules.</p>
<p>To access a particular rendering method referenced by a
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>, use plain attribute access:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="n">some_namespace</span><span class="o">.</span><span class="n">foo</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p><a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> also contains several built-in attributes
described here.</p>
<dl class="attribute">
<dt id="mako.runtime.Namespace.attr">
<tt class="descname">attr</tt><a class="headerlink" href="#mako.runtime.Namespace.attr" title="Permalink to this definition">¶</a></dt>
<dd><p>Access module level attributes by name.</p>
<p>This accessor allows templates to supply &#8220;scalar&#8221;
attributes which are particularly handy in inheritance
relationships.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="inheritance.html#inheritance-attr"><em>Inheritable Attributes</em></a></p>
<p class="last"><a class="reference internal" href="#namespace-attr-for-includes"><em>Version One - Use Namespace.attr</em></a></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.Namespace.cache">
<tt class="descname">cache</tt><a class="headerlink" href="#mako.runtime.Namespace.cache" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <a class="reference internal" href="caching.html#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> object referenced
by this <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> object&#8217;s
<a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>.</p>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.Namespace.context">
<tt class="descname">context</tt><em class="property"> = None</em><a class="headerlink" href="#mako.runtime.Namespace.context" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> object for this <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>.</p>
<p>Namespaces are often created with copies of contexts that
contain slightly different data, particularly in inheritance
scenarios. Using the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> off of a <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> one
can traverse an entire chain of templates that inherit from
one-another.</p>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.Namespace.filename">
<tt class="descname">filename</tt><em class="property"> = None</em><a class="headerlink" href="#mako.runtime.Namespace.filename" title="Permalink to this definition">¶</a></dt>
<dd><p>The path of the filesystem file used for this
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>&#8216;s module or template.</p>
<p>If this is a pure module-based
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>, this evaluates to <tt class="docutils literal"><span class="pre">module.__file__</span></tt>. If a
template-based namespace, it evaluates to the original
template file location.</p>
</dd></dl>

<dl class="method">
<dt id="mako.runtime.Namespace.get_cached">
<tt class="descname">get_cached</tt><big>(</big><em>key</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mako.runtime.Namespace.get_cached" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a value from the <a class="reference internal" href="caching.html#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> referenced by this
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> object&#8217;s <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>.</p>
<p>The advantage to this method versus direct access to the
<a class="reference internal" href="caching.html#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> is that the configuration parameters
declared in <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> take effect here, thereby calling
up the same configured backend as that configured
by <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt>.</p>
</dd></dl>

<dl class="method">
<dt id="mako.runtime.Namespace.get_namespace">
<tt class="descname">get_namespace</tt><big>(</big><em>uri</em><big>)</big><a class="headerlink" href="#mako.runtime.Namespace.get_namespace" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> corresponding to the given <tt class="docutils literal"><span class="pre">uri</span></tt>.</p>
<p>If the given <tt class="docutils literal"><span class="pre">uri</span></tt> is a relative URI (i.e. it does not
contain a leading slash <tt class="docutils literal"><span class="pre">/</span></tt>), the <tt class="docutils literal"><span class="pre">uri</span></tt> is adjusted to
be relative to the <tt class="docutils literal"><span class="pre">uri</span></tt> of the namespace itself. This
method is therefore mostly useful off of the built-in
<tt class="docutils literal"><span class="pre">local</span></tt> namespace, described in <a class="reference internal" href="#namespace-local"><em>local</em></a>.</p>
<p>In
most cases, a template wouldn&#8217;t need this function, and
should instead use the <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tag to load
namespaces. However, since all <tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt> tags are
evaluated before the body of a template ever runs,
this method can be used to locate namespaces using
expressions that were generated within the body code of
the template, or to conditionally use a particular
namespace.</p>
</dd></dl>

<dl class="method">
<dt id="mako.runtime.Namespace.get_template">
<tt class="descname">get_template</tt><big>(</big><em>uri</em><big>)</big><a class="headerlink" href="#mako.runtime.Namespace.get_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> from the given <tt class="docutils literal"><span class="pre">uri</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">uri</span></tt> resolution is relative to the <tt class="docutils literal"><span class="pre">uri</span></tt> of this <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>
object&#8217;s <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="mako.runtime.Namespace.include_file">
<tt class="descname">include_file</tt><big>(</big><em>uri</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mako.runtime.Namespace.include_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Include a file at the given <tt class="docutils literal"><span class="pre">uri</span></tt>.</p>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.Namespace.module">
<tt class="descname">module</tt><em class="property"> = None</em><a class="headerlink" href="#mako.runtime.Namespace.module" title="Permalink to this definition">¶</a></dt>
<dd><p>The Python module referenced by this <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>.</p>
<p>If the namespace references a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>, then
this module is the equivalent of <tt class="docutils literal"><span class="pre">template.module</span></tt>,
i.e. the generated module for the template.</p>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.Namespace.template">
<tt class="descname">template</tt><em class="property"> = None</em><a class="headerlink" href="#mako.runtime.Namespace.template" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object referenced by this
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>, if any.</p>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.Namespace.uri">
<tt class="descname">uri</tt><em class="property"> = None</em><a class="headerlink" href="#mako.runtime.Namespace.uri" title="Permalink to this definition">¶</a></dt>
<dd><p>The URI for this <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>&#8216;s template.</p>
<p>I.e. whatever was sent to <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><tt class="xref py py-meth docutils literal"><span class="pre">TemplateLookup.get_template()</span></tt></a>.</p>
<p>This is the equivalent of <tt class="xref py py-attr docutils literal"><span class="pre">Template.uri</span></tt>.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="mako.runtime.TemplateNamespace">
<em class="property">class </em><tt class="descclassname">mako.runtime.</tt><tt class="descname">TemplateNamespace</tt><big>(</big><em>name</em>, <em>context</em>, <em>template=None</em>, <em>templateuri=None</em>, <em>callables=None</em>, <em>inherits=None</em>, <em>populate_self=True</em>, <em>calling_uri=None</em><big>)</big><a class="headerlink" href="#mako.runtime.TemplateNamespace" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">mako.runtime.Namespace</span></tt></a></p>
<p>A <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> specific to a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> instance.</p>
<dl class="attribute">
<dt id="mako.runtime.TemplateNamespace.filename">
<tt class="descname">filename</tt><a class="headerlink" href="#mako.runtime.TemplateNamespace.filename" title="Permalink to this definition">¶</a></dt>
<dd><p>The path of the filesystem file used for this
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>&#8216;s module or template.</p>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.TemplateNamespace.module">
<tt class="descname">module</tt><a class="headerlink" href="#mako.runtime.TemplateNamespace.module" title="Permalink to this definition">¶</a></dt>
<dd><p>The Python module referenced by this <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>.</p>
<p>If the namespace references a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>, then
this module is the equivalent of <tt class="docutils literal"><span class="pre">template.module</span></tt>,
i.e. the generated module for the template.</p>
</dd></dl>

<dl class="attribute">
<dt id="mako.runtime.TemplateNamespace.uri">
<tt class="descname">uri</tt><a class="headerlink" href="#mako.runtime.TemplateNamespace.uri" title="Permalink to this definition">¶</a></dt>
<dd><p>The URI for this <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>&#8216;s template.</p>
<p>I.e. whatever was sent to <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><tt class="xref py py-meth docutils literal"><span class="pre">TemplateLookup.get_template()</span></tt></a>.</p>
<p>This is the equivalent of <tt class="xref py py-attr docutils literal"><span class="pre">Template.uri</span></tt>.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="mako.runtime.ModuleNamespace">
<em class="property">class </em><tt class="descclassname">mako.runtime.</tt><tt class="descname">ModuleNamespace</tt><big>(</big><em>name</em>, <em>context</em>, <em>module</em>, <em>callables=None</em>, <em>inherits=None</em>, <em>populate_self=True</em>, <em>calling_uri=None</em><big>)</big><a class="headerlink" href="#mako.runtime.ModuleNamespace" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">mako.runtime.Namespace</span></tt></a></p>
<p>A <a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> specific to a Python module instance.</p>
<dl class="attribute">
<dt id="mako.runtime.ModuleNamespace.filename">
<tt class="descname">filename</tt><a class="headerlink" href="#mako.runtime.ModuleNamespace.filename" title="Permalink to this definition">¶</a></dt>
<dd><p>The path of the filesystem file used for this
<a class="reference internal" href="#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>&#8216;s module or template.</p>
</dd></dl>

</dd></dl>

<dl class="function">
<dt id="mako.runtime.supports_caller">
<tt class="descclassname">mako.runtime.</tt><tt class="descname">supports_caller</tt><big>(</big><em>func</em><big>)</big><a class="headerlink" href="#mako.runtime.supports_caller" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a caller_stack compatibility decorator to a plain
Python function.</p>
<p>See the example in <a class="reference internal" href="#namespaces-python-modules"><em>Namespaces from Regular Python Modules</em></a>.</p>
</dd></dl>

<dl class="function">
<dt id="mako.runtime.capture">
<tt class="descclassname">mako.runtime.</tt><tt class="descname">capture</tt><big>(</big><em>context</em>, <em>callable_</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mako.runtime.capture" title="Permalink to this definition">¶</a></dt>
<dd><p>Execute the given template def, capturing the output into
a buffer.</p>
<p>See the example in <a class="reference internal" href="#namespaces-python-modules"><em>Namespaces from Regular Python Modules</em></a>.</p>
</dd></dl>

</div>
</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="runtime.html" title="previous chapter">The Mako Runtime Environment</a>
        Next:
        <a href="inheritance.html" title="next chapter">Inheritance</a>

    <div id="docs-copyright">
        &copy; Copyright the Mako authors and contributors.
        Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3 
        with Mako templates.
    </div>
</div>

</div>

<div class="clearfix">

<hr/>

<div class="copyright">Website content copyright &copy; by Michael Bayer.
    All rights reserved.  Mako and its documentation are licensed
    under the MIT license.  mike(&)zzzcomputing.com</div>

</div>
</div>
</body>
</html>
